Introduction to XML

Avoiding Bad Data

As you know, XML is an excellent way to store data. But it's also a great way to communicate it. Organizations often use XML to send data back and forth, and they include schema files to prevent misunderstandings.

Perhaps even more important than looking for structural errors, remember that a schema can also let you know if your XML content is wrong.

Consider this mix-up: Your company sent a boatload of armchairs from North Carolina to Quebec two months late, and as a result they couldn't fulfill hundreds of holiday gift orders. Their customers are angry, and the company is beyond angry.

What went wrong? Your order fulfillment software misinterpreted their 2016-12-10 Québécois date format. In the United States, 12-10 means December 10, but in Quebec, it's October 12.

Whoops! To prevent problems like this next time, you'll want to ask your customers to send a schema along with their XML order document. The schema will contain a date pattern that can't be misunderstood. Perhaps it'll be the official XML date pattern: YYYY-MM-DD—where 2016-10-12 has to mean October 12.

<shipdate type="date">2016-10-12</shipdate>

There are many official XML data types and subtypes you can use with schemas. Here are some of the most common:

• Integer (a number with no decimal point)
• Decimal (has a decimal point)
• AnyURI (a location, such as a Web page)
• DateTime
• String

But in addition to the major data types, there are many derived types (or subtypes), such as the token—a string with no whitespace, or the positiveInteger. And you can further refine types by using constraints—for example with the decimal type, you can specify an exact number of decimal places.

Just Google "xml schema data types" for a complete list. But always include data type specifications in your schema whenever you need to avoid ambiguity.

Let's Chat!

Date mix-ups are notorious, because different countries—even people in the same country—format dates differently. Can you think of another danger zone, another type of information that might cause problems because people express it in various ways? Join your classmates in the Discussion Area to share your ideas.

Creating a VB Validator

Earlier in this lesson, you validated the recipes.xml file using the validation tool built into VS. Now let's see how to write a VB program that validates. You'll import VB's XML.Schema library and use a couple of its commands.

Not so fast, I can hear you saying. What's the point of writing this VB program? Why not just use the built-in VS Schema validating feature like we just did in this lesson?

Good question.

XML Challenge!!

XML Challenge!

Can you think of a reason why using a VB validating program would be better than just using the validator built into VS?

Three reasons:

1. Using a VB program is faster than loading the files into VS, opening the XML Schema dialog box, associating the schema in the Properties window, opening the Error List, and so on. In other words, automation is usually faster and more reliable than managing information by hand.
2. You can custom design your VB program so people with zero knowledge of XML, schemas, VS, and all the rest can still accurately validate XML data.
3. As always, when you write your own custom VB program, you have complete control over its features and appearance. You can modify it any time.

The C:\XML L8 Finished folder includes a VB Validator program. You might want to view it now in VS to test the code or customize the program. To see the Validator, double-click the Validator.sln file your C:\XML L8 Finished\Validator folder. It will load into the VB editor.

Okay, let's look at the code that makes the validator do its job.

Looking at the Code

• Line 2 imports a code library with schema-related commands. We use its ValidationEventHandler object and ValidationEventArgs type in our code. VB has lots of built-in commands, but sometimes for specific kinds of programming (like working with XML or schemas), you must use the Imports command to add libraries of specialized commands. (Technically, Imports doesn't precisely add any commands—they're already in VB. Imports just allows you to avoid having to specify their library name every time you use them in your code.)

• Lines 10 and 11 should be familiar from previous lessons. They create an XML document object and then fill it with a complete copy of recipes.xml.

• Line 13 adds your .xsd schema file to the document object.

• Line 15 declares (Dim) and also creates (New), a validation event handler object.

• Line 17 tells VB to validate and to send any error messages to the event hander to display them to the user.

• Line 19 says that if our strMessage variable is empty, that means the event handler was never triggered. In other words, the validation process detected no errors. So we show that message to the user.

• Line 30 adds error message text to our strMessage variable every time an error is detected.

 += is just a shortcut way of appending new text to a text variable. The vbCrLf symbol is like pressing ENTER—it moves the text down one line to separate each error with some whitespace.

The End Command

If you're wondering about the End command in line 23, it's not essential. It just prevents VB from displaying Form1. And we're using a message box in this program rather than the form to communicate with the user, so the form can remain hidden.

Testing the Validator

To test the validator, change the title data type to xs:integer in the .xsd file. Recall that this will trigger an error because the title elements are text, not numeric digits:

<xs:element name="title" type="xs:integer" />

Then, after saving the recipes.xsd file with this change, press F5 to run the validation. You should see the message box shown here:

Three invalid-data-type errors

Importing a Recipe From the Clipboard

What's the easiest way for the user to add new recipes to their cookbook? Import them. It takes only three steps:

1. Select a recipe by dragging your mouse over it to highlight it.
2. Press CTRL + C to copy it.
3. Click the Import button in the cookbook program.

The program automatically adds all the necessary XML tags and saves the recipe into the recipes.xml file.

You can import recipes this way from the Internet, from Notepad, or from anywhere else you can select a recipe. Just one word of warning: The cookbook program distinguishes a recipe's title from its instructions by a carriage return (pressing the ENTER key to move to a new line). So you should have at least two paragraphs in any recipe you select—the first paragraph is the title, followed by as many additional paragraphs as you want for the instructions. The cookbook program will warn you if you attempt to import a single-paragraph recipe.

If a recipe's instructions are super long and overflow the textbox, the user can press the down-arrow or up-arrow keys to scroll the text. Alternatively, you can add a scrollbar. Just click the textbox in the Design window to select it, and then click the down arrow next to ScrollBars in the Properties window, and choose the Vertical scrollbar.

Okay, now we'll examine the code I wrote to import recipes:

Exploring the Code

Follow these steps:

1. Double-click cookbook.sln in the C:\XML L8 Finished\Cookbook folder to load the program into the editor.
2. Double-click Form1.vb in the Solution Explorer.
3. Double-click the Import button on the form to get to the Code window.

Let's look at the code this sub uses to import from the clipboard—and we'll discuss how it works.

• Declare three text variables: One variable holds the entire recipe, one holds the title only, and one holds the instructions only. When you import from the clipboard, text arrives as a single block, though it may have embedded tabs, carriage returns, and other whitespace. We'll need to separate the text into two chunks: the title and the instructions.

Dim WholeRecipe As String

Dim strTitle As String

Dim strInstructions As String

• Declare an integer variable. This numeric variable acts as a pointer. It will hold the index number of the first carriage return (CrLf) in the recipe. (Remember that the first CrLf  shows where the title ends and the instructions begin.)

Dim intPointer As Integer

• Handle any errors. If VB detects a problem, it jumps (GoTo) down to the line labeled "PROBLEM: (you can label this line ErrorHandler:, CancelSub:,AlertUser:, or anything else you wish)." When you name a line (ending with a colon), you've created a label you can jump to if something goes wrong.
  
  What could go wrong here? Lots of things. Maybe the user pressed the PRTSCN button, filling the clipboard with a screen image instead of text. Anyway, this code prevents the program from crashing:

On Error GoTo PROBLEM

• Import the recipe from Windows's clipboard. The Clipboard.GetText command assigns whatever text is currently in the clipboard to our variable WholeRecipe.

WholeRecipe = Clipboard.GetText

• Vacuum unwanted characters from the start and end of the recipe text.

These two lines delete any carriage returns, line feeds, tabs, or other such nonalphabetic formatting. They stop when they reach normal alphabetic or digit characters. This leaves your recipe clean, containing only ordinary text. If you don't remove this formatting stuff, your title might be simply a tab character rather than text. Recipes that the user copies from the Internet are especially likely to contain all sorts of debris.

• Separate the title and the instructions. This code divides the WholeRecipe text into two chunks. First, you locate the position of the CrLf (the ENTER key) character within the text:

intPointer = WholeRecipe.IndexOf(ControlChars.CrLf, 0)

Then, you put the text characters to the left of the CrLf (characters from zero to the pointer) into the strTitle variable. Finally, you put all the characters from the right of the pointer (plus 1 because you don't want to include the CrLf character) into the strInstructions variable.

        strTitle = WholeRecipe.Substring(0, intPointer)


        strTitle = strTitle.Replace("'", "")


strInstructions = WholeRecipe.Substring(intPointer + 1)

Notice the Replace command in the code above. This strips off any apostrophes in the title. If a recipe's title contains an apostrophe, like Uncle Bob's BBQ Sauce, the recipe will import, display correctly in the listbox, store in the XML file. But if you ever click on that title in the listbox, the program will crash and display an "invalid token" error message. Xpath, unfortunately, wasn't designed to handle apostrophes (or for that matter, quotation marks either).

The problem is that XPath itself uses apostrophes for its own purposes: to indicate the end of a text string. As a result, the following code in the lstTitles_Click event chokes on any apostrophes within title text:

IndividualRecipe = doc.SelectSingleNode("descendant::recipe[title='" & lstTitles.SelectedItem & "']")

My workaround is to just strip apostrophes from titles. (You can use them in the instructions with no problem.) If you really want to use apostrophes in your titles, feel free to look for a solution. You'll find a couple of suggestions in the Supplementary Material section of this lesson.

• Append the current month, year to the instructions. Maybe you've got 11 recipes for baked beans, but you want to search for only the most recent (presumably improved) recipe. Just type 2014 into the search field, thereby skipping those early, nasty student-days experiments involving Ramen. The following line of code adds the current month and year to the instructions:

strInstructions = strInstructions & vbCrLf & vbTab & vbTab & Now.ToString("MMMM, yyyy")

The Now command provides the current date. VB includes many formats you can use for dates and time. For example, if you change yyyy to yy, you'll display May, 14 rather than May, 2014. Just Google "VB date format" to see all the variations.

• Display the newly imported title in the listbox and the instructions in the textbox.

lstTitles.Items.Add(strTitle)

txtInstructions.Text = strInstructions

• Select the correct title in the listbox. Unless you specify otherwise, the listbox will highlight the first title in the list. But the imported recipe might well not be the first. And seeing the wrong title selected would upset some users. So this code fixes the potential mismatch by finding the new title in the listbox and then selecting it with the SelectedIndex method.

lstTitles.SelectedIndex = lstTitles.FindString(strTitle)

• Append the imported recipe to the XML document, and replace the recipes.xml file with this new version. These lines of code do the following jobs:

• Create a new <recipe>  element

Dim IndividualRecipe As XmlElement = doc.CreateElement("recipe")

•  Create its two children

Dim title As XmlElement = doc.CreateElement("title")

 Dim instructions As XmlElement = doc.CreateElement("instructions")

• Copy the imported title text into the new <title> element's InnerText (content)

title.InnerText = strTitle

• Copy the imported instructions text into the new < instructions> element's InnerText

instructions.InnerText = strInstructions

• Append these two child elements to their parent, the <recipe> element

IndividualRecipe.AppendChild(title)

 IndividualRecipe.AppendChild(instructions)

• Append the entire new <recipe> element to the bottom of the whole XML document

doc.DocumentElement.AppendChild(IndividualRecipe)

• Save the document to the hard drive

doc.Save(RecipesFilePath)

• Handle any errors. Remember above when we talked about the PROBLEM label? Here it is down at the bottom of the sub:

      Exit Sub


PROBLEM:


MsgBox("This recipe cannot be imported. Either there is an image in the clipboard instead of text. Or the text is a single paragraph. If so, press the Enter key after the recipe title. Then try importing again.")

If something goes wrong, it's far better to display a message to the user than to have your program abruptly stop with no explanation. User's justifiably hate that. Instead, describe the problem and tell them the solution.

It's necessary to put the Exit Sub command above the error handler label PROBLEM. If you don't do that, the program will display this error message every time the Import event executes—whether or not there was a problem.

By adding the Exit Sub command, the code executes normally and then quits (exits) without displaying this message to the user. Only if VB runs into a problem does execution jump over all the code (not attempting to import) and land here at the PROBLEM label where it tells the reader why the importing failed.

Recall that early on in this event, we told VB "if something goes wrong, stop executing any further instructions and go directly to the PROBLEM: label."

On Error GoTo PROBLEM

Using the Dreaded GoTo Command

We're playing with fire in this lesson's code by using the notorious and widely condemned GoTo command. In the early days of personal computer programming (1970-1980), programmers badly misused GoTo. People wrote code that jumped around here and there with wild abandon. It was so hard to read, maintain, and follow a path of execution so complicated that people called it spaghetti code. Instead of stepping down from line to line in order, execution would leap here, then there—all over the place.

Teachers rightly warned their students to avoid GoTo, advising that they should create a new sub any time they're tempted to use GoTo.

GoTo  has survived for use in this one, specialized error-handling technique (On Error GoTo) that we're using in our code. Even so, some experts still prefer that you use centralized error-handling (creating a sub that handles errors for the whole program).

All right, it's time to put this importing into practice.

Importing Recipes

To practice using the cookbook program's Import feature, follow these steps:

1. Find a recipe to import by clicking this link:

   http://richardm52.wordpress.com/

2. Drag your mouse over the Same-Day Sweet Pickles recipe to highlight (select) it.
3. Press CTRL+C to copy it to the Windows Clipboard.
4. Press F5 to run the cookbook program.
5. Click the Import button.

That's all there is to it! You've added a new recipe to the recipes.xml file. And whenever you want to add a new recipe after typing it into Notepad or Word or some other editor—just follow the same select-copy-click steps.

Click here to download the video transcript